<!DOCTYPE html>
<!-- saved from url=(0046)https://browserext.github.io/native-messaging/ -->
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
    <title>Native Messaging for Browser Extensions</title>
    
    <script src="https://www.w3.org/Tools/respec/respec-w3c-common" async="" class="remove"></script>
    <script class="remove">
      var respecConfig = {
	shortName: "native-messaging",
	edDraftURI:"https://browserext.github.io/native-messaging/",

	specStatus: "CG-DRAFT",
	editors: [
	  {
	    name: "Andrew Swan",
	    company:"Mozilla"
	  },
	  {
        name: "Mike Pietraszak",
        company: "Microsoft Corporation "
      }
],

	wg: "Browser Extension Community Group",
	wgURI: "https://www.w3.org/community/browserext/",

	otherLinks: [{
	  key: 'Participation',
	  data: [
	    {
	      value: 'GitHub repository',
	      href: 'https://github.com/browserext/native-messaging/'
	    },
	    {
	      value: 'File a bug / view open issues',
	      href: 'https://github.com/browserext/native-messaging/issues'
	    }
	  ]
	}],
      };
    </script>
  </head>
  <body>
    <section id="abstract">
      <p>
      Various applications of <a href="https://browserext.github.io/browserext/">Browser Extensions</a>
      need a mechanism to communicate with local client native processes outside of the browser environment.
      This specification proposes such a mechanism.
      </p>
    </section>
    <section id="sotd">
      <p>
      If you wish to make comments regarding this document, please file issues on
      <a href="https://github.com/browserext/native-messaging/issues/">github</a>.
      A <a href="mailto:public-browserext@w3.org">public mailing list</a> 
      (<a href="mailto:public-browserext-request@w3.org?subject=subscribe">subscribe</a>,
      <a href="http://lists.w3.org/Archives/Public/public-browserext/">archives</a>)
      is also available,
      but is reserved for high level discussions,
      and is not appropriate for specific comments about this document.
      </p>

      <p>
      Work on this document is governed by
      <a href="http://browserext.github.io/charter/">the charter</a> of the Browser Extension CG,
      which includes among other things the <a href="http://browserext.github.io/charter/#communication">Communication</a>,
      <a href="http://browserext.github.io/charter/#decision-policy">Decision</a>,
      and <a href="http://browserext.github.io/charter/#contribution-mechanics">Contribution</a> policies
      of this community group.
      </p>

      <div class="warning" id="inactive-cg">
          <p>Implementation of the technologies discussed and specified in this Community Group is ongoing
          and none of the original contributors have expressed opposition
          to this work.
          However, due to various circumstances,
          the level of participation has drooped below the level
          at which productive discussion is possible,
          and this group has become dormant as a result.
          </p>

          <p>The specifications have therefore not been maintained in a while,
          and are likely to be out of date.
          Issues can be raised and comments can be added to existing ones,
          but timely responses are unlikely at best.
          </p>

          <p>People interested in this work being resumed are encouraged
          to drum up support among the various implementors.
          </p>
	</div>
    </section>

    <section class="informative">
      <h2>Introduction</h2>
      <p>The Browser Extensions Community Group's goal is to make browser extension code much more interoperable across browsers by specifying common extension interfaces and well-defined browser behavior. </p>
      <p>This specification defines the interfaces and behavior which enables extensions to communicate with local client native processes outside of the browser environment.</p>
      <p>It is not a goal of this specification to define:</p>
        <ul>
            <li>The mechanism a browser would use to communicate with the local client native process (e.g. stdio)</li>
            <li>The registration specifics of how a browser would locate the local client native process app, service, or binary executable</li>
            <li>The specifics of how a browser would the lifetime of local client native process</li>
        </ul>
    </section>

    <section class="informative">
        <h2>Core APIs</h2>
        <p>The goal for these APIs is to provide functionality that extension authors need for message-passing between extensions and local client native process outside of the browser. Methods are provided for both establishing long-lived connection ports and for sending individual "one-shot" messages.</p>
        <section>
            <h4 id="runtime">The <code>runtime</code> object</h4>
            <section class="introductory">
                <h4>Overview</h4>
                <p>
                    In addition to the base functionality of the <code>browser.runtime</code> object defined in the [[!browserext]] Browser Extensions specification, these additional APIs provide functionaly for Native Messaging.
                </p>
            </section><section class="introductory">
                <h4>Manifest</h4>
                <p>
                    The <code>"nativeMessaging"</code> permission is required to use these additional APIs.
                </p>
<pre>{
    "permissions": [                               // Required
        "nativeMessaging"                          // Required
    ]                                              // Required   
}
</pre>
            </section>
            <section class="introductory">
                <h4>Context</h4>
                <p>
                    This API is available only in background pages, a subset of the Window context.
                </p>
            </section>
            <section class="introductory">
                <h4>WebIDL Definition</h4>
                <p>
                    A description of the special WebIDL syntax considerations for browser extensions are defined elsewhere in the [[!browserext]] Browser Extensions specification.
                </p>
<pre class="def idl">dictionary BrowserExtRuntimePort {
    Function disconnect;
    DOMString name;
    object onDisconnect;
    object onMessage;
    Function postMessage;
    MessageSender sender;
};
callback BrowserExtRuntimeSendNativeMessageCallback = void (any response);
[NoInterfaceObject]
partial interface BrowserExtBrowserRuntimeNativeMessaging {
    BrowserExtRuntimePort connectNative(DOMString nativeServiceName);
    void sendNativeMessage(DOMString nativeServiceName, object message, optional RuntimeSendNativeMessageCallback callback);
    attribute BrowserExtRuntimePort Port;
};
[NoInterfaceObject, Exposed=Window,CheckAnyPermissions="nativeMessaging"]
interface BrowserExtRuntimeNativeMessagingAPI {
    readonly attribute BrowserExtRuntimeNativeMessaging runtime; 
};
Browser implements BrowserExtRuntimeNativeMessagingAPI;

</pre>
            </section>
        </section>
    </section>

    <section class="informative">
        <h2>Local Client Native Process Registration</h2>
        <p>The local client native process must register itself in such a way that the browser will be able to:</p>
        <ul>
            <li>Locate the associated native component on the local client</li>
            <li>Start the local client native process when needed</li>
            <li>Filter the sending of messages to the local client native process, only allowing specified extensions to send messages</li>
        </ul>
        <p>Each browser implementation may have different mechanisms for registration, message filtering and lifetime management of the local client native process.</p>
    </section>
      <script>
        function updateCheckAnyPermissions() {
            var checkAnyPermissionsToken = "Ck_Any_Prm_";
            var e = document.body.getElementsByTagName("pre");
            var n = e.length;
            var q1 = -1;

            for (var i = 0; i < n; i++) {
                var s = e[i].innerHTML;
                if (s.indexOf(checkAnyPermissionsToken) >= 0) {
                    q1 = s.indexOf(checkAnyPermissionsToken) + checkAnyPermissionsToken.length;
                    q2 = s.indexOf("_", q1);
                    s = s.substring(0, q2) + '"' + s.substring(q2+1,s.length);
                    e[i].innerHTML = s.replace(checkAnyPermissionsToken, 'CheckAnyPermissions="');

                }
            }
        }
        setTimeout(" updateCheckAnyPermissions()", 2000);
      </script>
  

</body></html>